docs: bootstrap learning interoperability contracts - #1

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands.}

@opencode-agent Please review the current exact head 8bbfee6e3e216f3856184318f9779fcffa509972 against the develop base. Focus on standards truthfulness, repository authority boundaries, schema/versioning safety, licensing/certification claims, and whether the bootstrap can safely land as a documentation/contracts baseline. Do not rely on earlier heads.

@opencode-agent Re-review current exact head de6146ef09fcebca5fbf93007f7501d6a2dfb6bc against develop. Previous review evidence is stale. Verify the addressed CodeRabbit findings: accepted authority ADR, per-standard revision/normative-source/evidence-state traceability, versioned schema identity/path, and timestamp assertion policy. Return a current-head semantic verdict only.

You are seeing this message because GitHub Code Scanning has recently been set up for this repository, or this pull request contains the workflow file for the Code Scanning tool.

What Enabling Code Scanning Means:

• The 'Security' tab will display more code scanning analysis results (e.g., for the default branch).
• Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results.
• You will be able to see the analysis results for the pull request's branch on this overview once the scans have completed and the checks have passed.

For more information about GitHub Code Scanning, check out the documentation.

Current-head merge gate recheck — 2026-08-27

Exact head remains de6146ef09fcebca5fbf93007f7501d6a2dfb6bc; the PR is Ready, mergeable, and targets develop.

Verified current evidence:

• Learning Contracts Quality exact-head run 32262363457: success
• current-head opencode-review: success
• current-head coverage-evidence: success
• current-head coverage-source-tree: success
• no failed, queued, or in-progress check run was found on the current head
• all three CodeRabbit inline threads are resolved and outdated

Remaining merge blocker:

• no qualifying independent current-head approval is present; the only submitted review is a CodeRabbit COMMENTED review anchored to predecessor commit 8bbfee6e...

Please perform an independent semantic review of exact head de6146ef09fcebca5fbf93007f7501d6a2dfb6bc. Do not merge solely from green checks or the predecessor review. Once a qualifying current-head approval exists, re-fetch the head and live rules before enabling or executing the protected merge.

Dependent Draft PR #5 is stacked exactly one commit above this head and must be retargeted to develop only after this bootstrap PR integrates.

@coderabbitai review

Please review exact current head de6146ef09fcebca5fbf93007f7501d6a2dfb6bc; predecessor findings are resolved/outdated. Treat green Checks as evidence, not semantic approval.

#!/bin/bash
set -euo pipefail

requested='de6146ef09fcebca5fbf93007f7501d6a2dfb6bc'

printf '%s\n' '== Current revision =='
git rev-parse HEAD
git cat-file -t "$requested"
git merge-base develop "$requested"

printf '%s\n' '== Changed files against develop =='
git diff --name-status develop..."$requested"

printf '%s\n' '== Diff against develop =='
git diff --no-ext-diff --unified=80 develop..."$requested" -- \
  AGENTS.md CLAUDE.md CHANGELOG.md README.md \
  docs/ARCHITECTURE.md \
  docs/adr/0001-contract-authority-boundary.md \
  docs/doctoring/STANDARD_TRACEABILITY.md \
  schemas/learning-event.schema.json

printf '%s\n' '== JSON Schema parse validation =='
python3 - <<'PY'
import json
from pathlib import Path
path = Path("schemas/learning-event.schema.json")
data = json.loads(path.read_text(encoding="utf-8"))
print(f"valid JSON: {path}")
for key in ("$schema", "$id", "title", "type", "required", "properties", "additionalProperties"):
    print(f"{key}: {data.get(key)!r}")
PY

printf '%s\n' '== References to standards, certification, licensing, and timestamp fields =='
rg -n -i -C 3 \
  '(xapi|cmi5|lti|qti|case|open badges|clr|wcag|atag|iso|certif|conform|licen[cs]|timestamp|occurred|recorded|time)' \
  AGENTS.md CLAUDE.md CHANGELOG.md README.md docs schemas

#!/bin/bash
set -euo pipefail

schema='schemas/v1/learning-event.schema.json'
workflow='.github/workflows/quality.yml'
requested='de6146ef09fcebca5fbf93007f7501d6a2dfb6bc'

printf '%s\n' '== Actual schema and workflow diff =='
git diff --no-ext-diff --unified=120 develop..."$requested" -- "$schema" "$workflow"

printf '%s\n' '== Schema JSON and key locations =='
python3 - <<'PY'
import json
from pathlib import Path

path = Path("schemas/v1/learning-event.schema.json")
schema = json.loads(path.read_text(encoding="utf-8"))
print(f"valid JSON: {path}")
for key in ("$schema", "$id", "title", "description", "type", "required", "additionalProperties"):
    print(f"{key}: {schema.get(key)!r}")
print("properties:")
for name, definition in schema.get("properties", {}).items():
    print(f"  {name}: {json.dumps(definition, sort_keys=True)}")
PY

printf '%s\n' '== All contract references and schema validation commands =='
rg -n -C 4 \
  '(schemas/v1/learning-event\.schema\.json|learning-event\.schema\.json|jsonschema|check-jsonschema|ajv|eventVersion|occurredAt|recordedAt|timestamp|date-time)' \
  README.md AGENTS.md CLAUDE.md CHANGELOG.md docs .github

printf '%s\n' '== Repository license files and licensing references =='
fd -HI -t f '^(LICENSE|COPYING)(\..*)?$' . -E .git -x sh -c 'echo "== $1 =="; sed -n "1,120p" "$1"' sh {} \;
rg -n -i -C 2 '(licen[cs]|copyright|trademark|certif)' \
  README.md AGENTS.md CLAUDE.md CHANGELOG.md docs .github schemas || true

@seonghobae, I reviewed exact head de6146ef09fcebca5fbf93007f7501d6a2dfb6bc against merge base ba2948de245448eab739329f1131a36b4e59a54d on develop.

I found two schema safety blockers.

1. Schema identity is mutable.
   schemas/v1/learning-event.schema.json, Line 3, sets $id to a develop branch URL. The contents at that URL can change after release. This conflicts with the ADR requirement that consumers use released contracts. Publish the schema with an immutable release identity, such as a version tag or versioned artifact URL. Do not use a branch URL as the canonical $id.

2. The timestamp constraint accepts invalid calendar timestamps.
   schemas/v1/learning-event.schema.json, Lines 12-13, uses a regex that accepts values such as 2026-02-30T14:00:00Z. Under JSON Schema Draft 2020-12, format is annotation-only unless the evaluator enables format assertion. Consumers that validate only the declared pattern will accept invalid timestamps. Define a portable assertion policy and add negative validation cases for invalid dates, invalid leap days, and invalid UTC offsets.

The repository authority boundary is clear. The accepted ADR aligns with the README and architecture document. The standards traceability matrix identifies revisions and distinguishes adoption from conformance evidence and certification. I found no unsupported conformance, certification, or license claim.

Verdict: Do not merge this bootstrap baseline until the two schema safety issues are fixed.

_{You are interacting with an AI system.}

@cwl-noema-review
@opencode-agent

Please review the exact current head de6146ef09fcebca5fbf93007f7501d6a2dfb6bc against develop. Review only: do not update branches, enable auto-merge, merge, or bypass protection. Focus on the contract-authority boundary, versioned public schema identity, timestamp validation, and standards traceability after all resolved CodeRabbit findings.